\section{XML}

Communication between the remote client(s) and the OSS server will be by an XML dialect known as Phase 2 Markup Language (P2ML). Each command will contain the following items:-

\begin{itemize}
\item An ID. This must be unique between clients and over time including reboots such as $<clientID>$@$<address>$:$<sequenceNo>$ e.g. cmm:TmcAdmin@150.204.240.123:55555
\item An action class. This determines the eoperation to be performed at the database. e.g. \emph{UpdateGroup}.
\item A number of parameters specific to the action class. These may be primitive values e.g. identifiers or may encapsulate details of complex object graphs such as observation specifications.
\end{itemize}

\begin{verbatim}
<p2ml:command id = "wc@150.204.240.123:1234567">
 <action class = "LockGroup">
 <param name = "groupID">
    645464646
 </param>
 <param name = "clientID">
    WCUser@TMC:john.smith
 </param>
</p2ml:command>
\end{verbatim}

The reply to a command which has completed successfuly should contain:-
\begin{itemize}
\item The ID of the original command.
\item A series of data parameters specific to the command's action class. These may be primitive values e.g. identifiers or may encapsulate details of complex object graphs such as observation specifications.
\end{itemize}

\begin{verbatim}
<p2ml:reply id = "wc@150.204.240.123:1234567">
 <data name = "key">
    8575757575
 </data>
</p2ml:reply>
\end{verbatim}

The reply to a command which has failed should contain:-
\begin{itemize}
\item The ID of the original command.
\item An error code selected from the set of valid codes (see \ref{errors}).
\item A message detailing the cause of the fault. This could contain substructure which can be parsed by a remote client.
\end{itemize}

\begin{verbatim}
<p2ml:error id = "wc@150.204.240.123:1234567">
 <code>758004</code> 
 <message>
   <text>The group is already locked</text>
   <user>jo.bloggs</user>
   <date>2005-12-18T12:45:08UTC</date>
   <client>nsoc@150.204.123.112</client>
 </message> 
</p2ml:error>
\end{verbatim}

Here is a big long example with structure within the request parameters.
\begin{verbatim}
<p2ml:command id = "wc@150.204.240.123:1234999">

 <action class = "UpdateObservation">

  <param name = "obsID">
    8575757
  </param>

  <param name = "obsHeader">

    <observation name = "obs-r4">

      <exposure>
        <time>300.0</time>
        <repeat>6</repeat>
      </exposure>

      <target>
        <targetID> 85858 </targetID>   
        <raOffset>  15.0 </raOffset>
        <decOffset> -3.5 </decOffset>
      </target>

      <instrument class = "ngat.phase2.CCDConfig">
        <filter wheel = "lower"> SDSS-B </filter>
        <filter wheel = "upper"> CLEAR  </filter>
        <bin>2</bin>
        <calibrate seq = "before"> TRUE  <calibrate>
        <calibrate seq = "after">  FALSE <calibrate>
      </instrument>

      <scope>
        <focusOffset>0.03</focusOffset>
        <autoguider use = "OPTIONAL"/>
        <rotator mode = "SKY" angle = "10.0"/>
      </scope>

      <mosaic pattern = "CROSS">
       <xOffset> 3.0 </xOffset>
       <yOffset> 0.2 </yOffset>
      </mosaic>      

    </observation>

  </param>

</p2ml:command>
\end{verbatim}

Here we give details of the XML used to describe the various phase2 objects when encapsulated in a P2ML command/reply xml wrapper. I wonder if we should be using JAXB or some other clever thing to do this for us !
